MacFormat 1995 March/macformat-022.iso/Shareware City/Developers/HoW Developer’s Kit 1.2/HoWSample/HoWSample Help/HoWSample Help.rsrc/STR#_1027.txt

Text File | 1994-10-17 | 12.1 KB | 637 lines






x


x





åBuilding a Help File





Here, I describe briefly what you have to do to make a help file.  These

instructions apply whether or not you’ve decided to make the help file a

real document, separate from your application.










xWhat Is a Help File?



Your Help on Wheels client application must have a help file, which the

server can open when it’s time to display help.  When it opens your help

file, the server needs to find and display the information fast.  Reading a

mixed text/graphic format would take too long, so Help on Wheels uses a

special format designed by John Norstad for his famous Disinfectant

anti-virus application.  This format consists of a collection of resources

which can be quickly read and translated into a list data structure,

complete with text, pictures, and indexing information.  As improved for

use with Help on Wheels, this format also allows for hypertext buttons

and multilingual help files.










xHow Do I Make One?



You will need the special “wrap” and “cvrt” MPW tools and the Rez file

HoWRez.{language}.r, provided in this developer’s kit, to produce a help

file in this format.  (A note to those familiar with Norstad’s source

archive:  These tools are not quite the same as the ones he provided, but

they do use the same syntax, so the syntax description included here is

his.  The tools provided are guaranteed to work correctly for all uses

described in these instructions.  Please address any questions about these

tools to me, not to Mr. Norstad.)  The HoWSample Make file shows how

the tools and Rez file were used to build this help file.





You may have noticed that this help file, viewed through the help server,

is a mixture of pictures and text.  The help source document, however, is

a plain text file.  When reading this section, you may want to compare

what you see through Help on Wheels with the help source document.



To produce a help source document for your application, you can use any

text editor which wraps long lines and is able to “save as text.”

TeachText is fine; Microsoft Word is good too, as long as you remember

to “save as text” and not to edit the pictures into the “.doc” file itself.

MPW Shell is not good for this purpose, because it doesn’t wrap long lines.








xWhat’s in a Source Document?



The paragraphs you see in a help file like this one are just long lines of

text in the help source document, with no carriage returns between lines.

(The “wrap” tool does the line wrapping for you; the help server will

re-wrap the lines when printing, according to the user’s Page Setup

specifications.)  There are usually two carriage returns between

paragraphs, to ensure some white space between.





Everything in a help source document that isn’t paragraph text is a

markup directive.  These directives are similar to those of markup

languages such as GML and nroff.  For example, the pictures you see in

this help file are stored in the help file as 'PICT' resources.  They were

positioned between paragraphs using a simple markup directive in the help

source document:



 \pict 429

Other markup directives let you set the justification and style of a

paragraph, like the centered italic text you have just read.  You also use

markup directives to put entries in the table of contents, break pages,

build keep blocks, and so on.








xHow Do I Index My Help File?



The table of contents built from your markup directives appears in the

server’s help window, so that the user can browse by topic.  It also

appears, complete with page numbers, at the front of the help file when

printed.  This method of indexing your help file is suitable for humans, but

not for your client application.





The other important use of markup directives is to put numeric tag values

on important points in the help file.  Tags have two main uses in Help on

Wheels help files.  First, they allow the client to summon information on a

specific topic by citing a tag value when asking the server to display the

help file.  The server will scroll the help file to make the tag point visible.

Second, they introduce blocks of information which the user can click to

cause an action.  These hypertext “buttons” may be single paragraphs or

pictures, or several together, such as a figure and its caption.



Hypertext tags are worth a closer look, because they can add a lot to the

impact of your help file.  Hypertext buttons in Help on Wheels are of two

types:  link buttons and hot buttons.  When the user clicks a link button,

the server scrolls to another part of the help file to display related

information.  With a hot button, the server activates the client and sends

it a Help event, telling it which button was clicked.  Your client can

respond in any way you think is appropriate.



Hypertext tags are distinguished from ordinary tags by their negative

numbers.  (Conventionally, hypertext paragraphs are underlined, but you

must insert the style directive to make this happen.)  The button extends

from the hypertext tag to the next tag.  You can use a “\tag 0” directive

to end a hypertext block, if you have no other reason to put a tag there.

The button is a link button only if there is another tag in the help file

whose number is the same, but positive, indicating the target of the link.

If there is no complementary target for the hypertext tag, then the button

is a hot button.








xPutting it Together



Here I describe what MPW commands you need to build a help file.  You

should make these commands part of your Make file, as is the case with

HoWSample.





The MPW tools “cvrt” and “wrap” can be piped together, so that your

help source document goes in one end, and your help file comes out the

other.  The following option values are standard for use with Help on

Wheels:  “wrap -r 335 -p”; “cvrt -w 345 -h 12”.  In addition, “cvrt”

needs to know the name of the file where the 'PICT' resources are stored

(“-p”), and the ID numbers for the generated 'STR#' (“-i”), 'TCON'

(“-t”), 'TAG ' (“-g”), and 'CELL' (“-c”) resources.  There may actually

be several 'STR#' resources, depending on the length of the source

document and the number of “\str#” directives in it.



[The following descriptions are reprinted from the source by John

Norstad.]





wrap -r xxxx [-p]



xxxx = right margin in pixels.



-p = if specified, add a special end-of-paragraph byte 31 to the end of

each line.







cvrt -o file1 -i nnn [-t aaa] [-g bbb] [-c ccc] [-p file2 -h xxx -w yyy]

[file3]



file1 = output resource file.

nnn = starting STR# resource id.

aaa = TCON resource id.

bbb = TAG resource id.

ccc = CELL resource id.

file2 = pict resource file.

xxx = height of report cells in pixels.

yyy = width of report cells in pixels.

file3 = input text file.



The text file is converted to a consecutive sequence of STR# resources

starting with id nnn.



The source text is intermixed with special cvrt directives.  Any line

starting with the character ‘\’ is treated as a directive.  Directives must

be all lower case.  The syntax checking by this tool is minimal.







 \str#



Starts a new STR# resource.







 \tcon title



Table of contents entry.  The title and the current line number (zero

based) are saved in the TCON resource.







 \tag nnn



Tag resource entry.  The number nnn and the current line number (zero

based) are saved in the TAG resource.







 \style xxx xxx xxx



The next text line is drawn in the specified style or styles.  xxx may be

any of the following:



normal (default)

bold

italic

underline

outline

shadow

condense

extend







 \just xxx



The next text line or picture is drawn with the specified justification.

xxx may be any of the following:



left        (default for text lines)

center      (default for pictures)

right







 \size xxx



Print the following line of text xxx% larger than normal.  Printing only.

The normal font size is multiplied by xxx%, then truncated.  For

non-laserwriters it is then rounded down to the nearest font size which

can be printed without Font Manager scaling.







 \only xxx xxx



The next text line or picture or table of contents entry should only be

output as specified.  xxx may be any of the following:



screen     Only in the report on the screen.

print      Only in the printed document.

save       Only in the saved document.



The default for text lines is:    screen print save

The default for pictures is:      screen print

The default for tcon entries is:  screen print







 \pict id



A picture from the pict resource file should be inserted at this point.

“id” is the resource id of the pict.







 \page noheader



Start a new page.  Printing only.  The “noheader” parameter is optional.

If the parameter is present, header printing is disabled until the next

“\page” directive is encountered.







 \keep



Keep the following block of text on the same page.  Force a page break if

necessary.  Printing only.  Paragraphs are always kept on a page, never

split across page boundaries.







 \endkeep



End a keep block.  Printing only.







 \itcon nnn



Insert table of contents.  Printing only.



nnn = total number of printing tcon entries.  This number must be adjusted

by hand whenever you add or remove tcon entries (sorry). It is verified

at the end of the cvrt run, and if it is incorrect the correct value is

printed in an error message (this helps a bit).





The same ID numbers you gave to “cvrt” should also appear in the Rez

command as values for the defined symbols “HoWi”, “HoWt”, “HoWg”,

and “HoWc”.  Another symbol “HoWa” specifies the ID number of the

generated 'ALRT', 'DITL', and 'STR ' resources.  If your help file is the

application itself, be careful not to choose ID numbers which collide with

any defined for your application’s own use.  All of these ID numbers

should be in the range allocated for applications (128 to 32767).  The

defined symbol “languageCode” can also be set.

See the section entitled “Language Support” for more details.



If your help file is separate from your application, it must have type

'HoW!' and creator 'HoW?' in order to be a double-clickable Help on Wheels

document.  As well as the necessary “-t” and “-c” options, your Rez

command should include an option of the form “-d

application=∂"HoWSample∂"” (or “-d extension=∂"HoWSampleExt∂"” if

your program is an extension or control panel) to direct

HoWRez.{language}.r to generate an alert string resource, which will help

the user get a readable TeachText version if the server is not available.



It is likely that your documentation will change over time.  If your help

file is separate from your application, new versions of the help file may

be incompatible with old versions of the application, and vice versa.  To

help prevent errors, Help on Wheels offers an optional client version

checking capability.  To use it, include options of the form “-d

version=0x0101 -d versionString=∂"1.0.1∂"” in your Rez command.

This will direct HoWRez.{language}.r to generate a version resource,

visible using Finder’s Get Info dialog.  HoWSample’s Make file and C

source code show how to tie these options to the application so that

version checking is enforced.  If the help file contains a version resource,

and the version code is not the same as that supplied by the application at

the time of registration, an error (wrongVersionErr) is returned to the

application.



You will need a separate Rez command to merge the 'PICT' resource file

into the help file, because the “cvrt” tool doesn’t do this for you.  The

HoWSample Make file shows one way to do this.